<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tk_MeasureChars manual page - Tk Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tk C API</a> <small>&gt;</small> MeasureChar</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="MeasureChar.htm#M2" NAME="L463">NAME</A>
<DL><DD>Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars &mdash; routines to measure and display simple single-line strings.</DD></DL>
<DD><A HREF="MeasureChar.htm#M3" NAME="L464">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tk.h&gt;</B>
<DD>int
<DD><B>Tk_MeasureChars(</B><I>tkfont, string, numBytes, maxPixels, flags, lengthPtr</I><B>)</B>
<DD>int
<DD><B>Tk_TextWidth(</B><I>tkfont, string, numBytes</I><B>)</B>
<DD><B>Tk_DrawChars(</B><I>display, drawable, gc, tkfont, string, numBytes, x, y</I><B>)</B>
<DD><B>Tk_UnderlineChars(</B><I>display, drawable, gc, tkfont, string, x, y, firstByte, lastByte</I><B>)</B>
</DL>
<DD><A HREF="MeasureChar.htm#M4" NAME="L465">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DD><A HREF="MeasureChar.htm#M5" NAME="L466">DESCRIPTION</A>
<DD><A HREF="MeasureChar.htm#M6" NAME="L467">SEE ALSO</A>
<DD><A HREF="MeasureChar.htm#M7" NAME="L468">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars &mdash; routines to measure and display simple single-line strings.
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tk.h&gt;</B><BR>
int<BR>
<B>Tk_MeasureChars(</B><I>tkfont, string, numBytes, maxPixels, flags, lengthPtr</I><B>)</B><BR>
int<BR>
<B>Tk_TextWidth(</B><I>tkfont, string, numBytes</I><B>)</B><BR>
<B>Tk_DrawChars(</B><I>display, drawable, gc, tkfont, string, numBytes, x, y</I><B>)</B><BR>
<B>Tk_UnderlineChars(</B><I>display, drawable, gc, tkfont, string, x, y, firstByte, lastByte</I><B>)</B><BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT><A HREF="../TkLib/GetFont.htm">Tk_Font</A> <B>tkfont</B> (in)<DD>
Token for font in which text is to be drawn or measured.  Must have been
returned by a previous call to <B><A HREF="../TkLib/GetFont.htm">Tk_GetFont</A></B>.
<P><DT>const char <B>*string</B> (in)<DD>
Text to be measured or displayed.  Need not be null terminated.  Any
non-printing meta-characters in the string (such as tabs, newlines, and
other control characters) will be measured or displayed in a
platform-dependent manner.
<P><DT>int <B>numBytes</B> (in)<DD>
The maximum number of bytes to consider when measuring or drawing
<I>string</I>.  Must be greater than or equal to 0.
<P><DT>int <B>maxPixels</B> (in)<DD>
If <I>maxPixels</I> is &gt;= 0, it specifies the longest permissible
line length in pixels.  Characters from <I>string</I> are processed only
until this many pixels have been covered.  If <I>maxPixels</I> is &lt; 0, then
the line length is unbounded and the <I>flags</I> argument is ignored.
<P><DT>int <B>flags</B> (in)<DD>
Various flag bits OR-ed together: <B>TK_PARTIAL_OK</B> means include a character
as long as any part of it fits in the length given by <I>maxPixels</I>;
otherwise, a character must fit completely to be considered.
<B>TK_WHOLE_WORDS</B> means stop on a word boundary, if possible.  If
<B>TK_AT_LEAST_ONE</B> is set, it means return at least one character even if no
characters could fit in the length given by <I>maxPixels</I>.  If
<B>TK_AT_LEAST_ONE</B> is set and <B>TK_WHOLE_WORDS</B> is also set, it means that if
not even one word fits on the line, return the first few letters of the
word that did fit; if not even one letter of the word fit, then the first
letter will still be returned.
<P><DT>int <B>*lengthPtr</B> (out)<DD>
Filled with the number of pixels occupied by the number of characters
returned as the result of <B>Tk_MeasureChars</B>.
<P><DT>Display <B>*display</B> (in)<DD>
Display on which to draw.
<P><DT>Drawable <B>drawable</B> (in)<DD>
Window or pixmap in which to draw.
<P><DT>GC <B>gc</B> (in)<DD>
Graphics context for drawing characters.  The font selected into this GC
must be the same as the <I>tkfont</I>.
<P><DT>int <B>x, y</B> (in)<DD>
Coordinates at which to place the left edge of the baseline when displaying
<I>string</I>.
<P><DT>int <B>firstByte</B> (in)<DD>
The index of the first byte of the first character to underline in the
<I>string</I>.  Underlining begins at the left edge of this character.
<P><DT>int <B>lastByte</B> (in)<DD>
The index of the first byte of the last character up to which the
underline will be drawn.  The character specified by <I>lastByte</I>
will not itself be underlined.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
These routines are for measuring and displaying simple single-font,
single-line strings.  To measure and display single-font, multi-line,
justified text, refer to the documentation for <B><A HREF="../TkLib/TextLayout.htm">Tk_ComputeTextLayout</A></B>.
There is no programming interface in the core of Tk that supports
multi-font, multi-line text; support for that behavior must be built on
top of simpler layers.
Note that the interfaces described here are
byte-oriented not character-oriented, so index values coming from Tcl
scripts need to be converted to byte offsets using the
<B><A HREF="../TclLib/Utf.htm">Tcl_UtfAtIndex</A></B> and related routines.
<P>
A glyph is the displayable picture of a letter, number, or some other
symbol.  Not all character codes in a given font have a glyph.
Characters such as tabs, newlines/returns, and control characters that
have no glyph are measured and displayed by these procedures in a
platform-dependent manner; under X, they are replaced with backslashed
escape sequences, while under Windows and Macintosh hollow or solid boxes
may be substituted.  Refer to the documentation for
<B><A HREF="../TkLib/TextLayout.htm">Tk_ComputeTextLayout</A></B> for a programming interface that supports the
platform-independent expansion of tab characters into columns and
newlines/returns into multi-line text.
<P>
<B>Tk_MeasureChars</B> is used both to compute the length of a given
string and to compute how many characters from a string fit in a given
amount of space.  The return value is the number of bytes from
<I>string</I> that fit in the space specified by <I>maxPixels</I> subject to
the conditions described by <I>flags</I>.  If all characters fit, the return
value will be <I>numBytes</I>.  <I>*lengthPtr</I> is filled with the computed
width, in pixels, of the portion of the string that was measured.  For
example, if the return value is 5, then <I>*lengthPtr</I> is filled with the
distance between the left edge of <I>string</I>[0] and the right edge of
<I>string</I>[4].
<P>
<B>Tk_TextWidth</B> is a wrapper function that provides a simpler interface
to the <B>Tk_MeasureChars</B> function.  The return value is how much
space in pixels the given <I>string</I> needs.
<P>
<B>Tk_DrawChars</B> draws the <I>string</I> at the given location in the
given <I>drawable</I>.
<P>
<B>Tk_UnderlineChars</B> underlines the given range of characters in the
given <I>string</I>.  It does not draw the characters (which are assumed to
have been displayed previously by <B>Tk_DrawChars</B>); it just draws the
underline.  This procedure is used to underline a few characters without
having to construct an underlined font.  To produce natively underlined
text, the appropriate underlined font should be constructed and used.
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TkCmd/font.htm">font</A></B>, <B>FontId</B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/F.htm#font">font</A>, <A href="../Keywords/M.htm#measurement">measurement</A>
<div class="copy">Copyright &copy; 1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
